<!DOCTYPE html>

<html>
<head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
    <title>Data Conduits - Raxan User Guide</title>
    <link href="../raxan/ui/css/master.css" rel="stylesheet" type="text/css" />
    <!--[if lt IE 8]> <link rel="stylesheet" href="../raxan/ui/css/master.ie.css" type="text/css"><![endif]-->
    <link href="../raxan/ui/css/default/theme.css" rel="stylesheet" type="text/css" />
    <link href="style.css" rel="stylesheet" type="text/css" />
    <link href="highlight/styles/default.css" rel="stylesheet" type="text/css" />
    <script type="text/javascript" src="highlight/highlight.js"></script>
    <script type="text/javascript">
        <!--
        hljs.initHighlightingOnLoad('javascript','html','php','css');
        //-->
    </script>
    <!--[if lt IE 7]>
        <style type="text/css"> form input.textbox { height: 26px; }</style>
    <![endif]-->
</head>

<body>
    <div class="container">
        <div id="header" class="rax-header-pal rax-metalic">
            <h2 class="ltm bottom c14">Raxan User Guide</h2>
            <ul>
                <li><a href="../../index.html">Home</a></li>
                <li><a href="index.html">Overview</a></li>
                <li><a href="features.html">Features</a></li>
                <li><a href="table-of-contents.html" title="Table of Content">Contents</a></li>
                <li><a href="../examples">Examples</a></li>
            </ul>
            <ul class="search">
                <li>
                    <form class="tpm c9" name="form1" action="../tools/search.php" method="get">
                        <input class="c6 textbox round left" placeholder="Search" type="text" name="q" value="" title="Search User Guide"  />
                        <input class="c2 button round left ltm" type="submit" value="Go" />
                    </form>
                </li>
            </ul>

        </div>
        <hr class="space"/>
        <div class="master-content-wrapper">
            <div class="container prepend-top c48 master-content"><h2>Asynchronous Data Conduits (experimental)</h2>

<p>Conduits are special data links between the client and the server. You can think of a data conduit as a pipe connecting a water tank to the kitchen faucet.
From within the kitchen you can control the amount of water coming into and out of pipe. This is exactly what Raxan data conduits do.</p>

<p>By using JavaScript you can dynamical control the flow of data to your web page. This means that you will be able page or loop through a range of
data records within the conduit.</p>

<pre><code class="javascript">&lt;script type="text/javascript"&gt;
    Raxan.ready(function(){
        var cn = Raxan.createConduit('customers');
        function loadPage(n) {
            cn.page(n, function(rowset,offset) {
                var lst = '';
                for(i in rowset) {
                    lst+='&lt;div&gt;'+rowset[i]['first_name']+'&lt;/div&gt;';
                }
                $('#result').html(lst);
            });
        }
    })
&lt;/script&gt;
</code></pre>

<p>When a conduit is connected to the server it sends a request to have data downloaded to the web page. This action triggers special data handlers that are used to return the data to the client.
Here's the what page execution cycle looks like during a conduit request:</p>

<ul>
<li>Configure Page</li>
<li>Initialize Page</li>
<li>Initialize Page View</li>
<li>Page Load           </li>
<li>Page Data Conduit handler (callback)</li>
<li>Page PreRender              </li>
<li>Page PostRender             </li>
<li>Page Reply                  </li>
<li>Destroy Page                </li>
</ul>

<p>The conduit API will automatically handle data caching, loading and navigation so that you can focus on what you want to do with the data.</p>

<h3>Creating a Conduit</h3>

<p>To create a conduit you will first need to register the conduit and the data handler:</p>

<pre><code class="php">&lt;?php
    protected function _init() {
        // register a conduit called myDataset
        $this-&gt;registerConduit('myDataset','.dataHandler');
    }

    protected function dataHandler($offset, $limit, $params, &amp;$rowcount){
        // use a .csv file for the data source
        $csv = $this-&gt;Raxan-&gt;importCSV('contacts.csv');
        if (rowcount==0) $rowcount = count($csv); // set rowcount
        $ds = array_slice($csv, $offset, $limit);
        return $ds; // returns the dataset as a 2D array
    }
?&gt;
</code></pre>

<p>From the browser you can use the <strong>Raxan.createConduit()</strong> to create a connection to the conduit.</p>

<p>Raxan.createConduit() Syntax:</p>

<pre><code>Raxan.createConduit(name,option)
</code></pre>

<p>Raxan.createConduit() Options:</p>

<ul>
<li><strong>bufferSize</strong> - Number of rows to be download at a time. Defaults to 50</li>
<li><strong>pageSize</strong> - Number of rows to be returned when requesting a page. Defaults to 10</li>
<li><strong>requestDelay</strong> - Sets the number of milli-seconds to wait before the request is processed. Defaults to 70ms.</li>
<li><strong>before</strong> - Function to be called before request is send to the server</li>
<li><strong>after</strong> - Function to be called after a response is received to the server</li>
<li><strong>error</strong> - Function to be called if an error occurred during a request</li>
</ul>

<p>To create a</p>

<pre><code class="javascript">&lt;script type="text/javascript"&gt;
    Raxan.ready(function() {

        // connect to the "myDataset" conduit using default settings
        var cn = Raxan.createConduit('myDataset');

        // create a custom connection
        var cn = Raxan.createConduit('myDataset',{
            bufferSize: 100,
            pageSize: 20,
            before: function(){ /* executed before conduit is called */ },
            after: function(){ /* executed after conduit is called  */ },
            error: function(conduit, result){
                if (result) alert('error:'+result);
                return true; // let Raxan know that the error was handled
            }
        });

    })
&lt;/script&gt;
</code></pre>

<p>After connecting to the server you can submit a request to download data when needed:</p>

<pre><code class="javascript">&lt;script type="text/javascript"&gt;        
    cn.first(function(row,offset){
        $('#list1').append('#'+offset+' - '+row['name']+'&lt;br&gt;');
    })
&lt;/script&gt;
</code></pre>

<h3>Data navigation</h3>

<p>Use the conduit JavaScript API to load and navigate data sets.</p>

<h4><strong>Move, Next, Prev...</strong></h4>

<p>To load the an individual data record use first(), next(), prev(), last(), or moveTo():</p>

<pre><code class="javascript">&lt;script type="text/javascript"&gt;

    // get first record
    cn.first(function(row,offset) {
        alert('First contact: ' + row['name']);
    });

    // get next record
    cn.next(function(row,offset) {
        alert('Next contact: ' + row['name']);
    });

    // get last record
    cn.last(function(row,offset) {
        alert('Last contact: ' + row['name']);
    });

    // get prev record
    cn.last(function(row,offset) {
        alert('Previous contact: ' + row['name']);
    });

    // move to record #10
    cn.moveTo(10,function(row,offset) {
        alert('Contact #'+(offset+1)+': ' + row['name']);
    });

&lt;/script&gt;
</code></pre>

<p>To retrieve a record without changing the current offset or position use the get method as shown below:</p>

<pre><code class="javascript">&lt;script type="text/javascript"&gt;
        //retrieve record #25 without changing the current position
        cn.get(25,function(row,offset) {
            alert('Contact #'+(offset+1)+': ' + row['name']);
        });
&lt;/script&gt;
</code></pre>

<h4><strong>Paging</strong></h4>

<p>A page is a set of data records based on the pageSize option value. If the pageSize option is set to 10 then the Raxan will download 10 records
from the server.</p>

<p>To load a page, use the page() method as shown below:</p>

<pre><code class="javascript">&lt;script type="text/javascript"&gt;
    // load page #1
    cn.page(1, function(rowset,offset){
        var i, row;
        for(i in rowset) {
            row = rowset[i];
            // append record to #content
            $('#content').append('Contact #'+(offset+1)+': ' + row['name']);
        }
    })        
&lt;/script&gt;
</code></pre>

<p>The page() method will retrieve the records from server (or data cache), then pass an array of records and the current offset to the callback function.</p>

<p>To retrieve the total number of page count use the pageCount() method:</p>

<script type="text/javascript">

    cn.first(function(){
        // get current page count
        var pages = cn.pageCount();
        alert('Total pages: '+pages);
    })
</script>

<h4><strong>Looping</strong></h4>

<p>To retrieve a set of records from the from the conduit, you can use the <strong>loop()</strong> and <strong>loopBy()</strong> method.  The loop() method requires a starting and ending
value for the range of records to be retrieved, while the loopBy() method only requires the number of records to be retrieved from the current offset:</p>

<pre><code class="javascript">&lt;script type="text/javascript"&gt;

    // retrieve the first 20 records (0-19)
    cn.loop(0,19,function(row, offset,index, length){
        var elm = $('#info');
        if (index==0) elm.html('').hide();
        if (index&lt;length) elm.append(row['name']+'&lt;br&gt;');
        if (index&gt;=length-1) elm.show;
    })

    // retrieve the next 10 records from the current offset
    cn.loopBy(10,function(row, offset, index, length){
        var elm = $('#info');
        if (index==0) elm.html('').hide();
        if (index&lt;length) elm.append(row['name']+'&lt;br&gt;');
        if (index&gt;=length-1) elm.show;
    })

&lt;/script&gt;
</code></pre>

<p>The "index" parameter represents the current index within the loop while the "length" parameter represents the number of items within the loop.
See the <a href="rjo.html">Raxan JavaScrit Object (RJO)</a> for more information.</p>

<hr class="clear" />

<p align="right">Up Next: <a href="rjo.html" title="Raxan JavaScript Object (RJO)">Raxan JavaScript Object</a> </p>
</div>
            
            <div id="footer" class="container c48 rax-active-pal round rax-glossy">
                <ul class="clearfix">
                    <li><a href="index.html">Overview</a></li>
                    <li><a href="features.html">Features</a></li>
                    <li><a href="new-features.html">What's new</a></li>
                    <li><a href="table-of-contents.html" title="Table of Content">Contents</a></li>
                    <li><a href="../examples">Examples</a></li>
                </ul>
            </div>
        </div>
    </div>
</body>

</html>

